From c65239155f93eb6fe1d38e203756f706cc415d6d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 27 Feb 2021 18:20:56 -0500 Subject: [PATCH] notebook: Convert docs --- gtk/gtknotebook.c | 461 ++++++++++++++++++++++++++++------------------ gtk/gtknotebook.h | 9 +- 2 files changed, 287 insertions(+), 183 deletions(-) diff --git a/gtk/gtknotebook.c b/gtk/gtknotebook.c index ed712517b4..3e65f125c8 100644 --- a/gtk/gtknotebook.c +++ b/gtk/gtknotebook.c @@ -59,24 +59,24 @@ #include /** - * SECTION:gtknotebook - * @Short_description: A tabbed notebook container - * @Title: GtkNotebook + * GtkNotebook: * - * The #GtkNotebook widget is a layout container whose children are - * pages that can be switched between using tab labels along one edge. + * `GtkNotebook` is a container whose children are pages switched + * between using tabs. * - * There are many configuration options for GtkNotebook. Among other - * things, you can choose on which edge the tabs appear - * (see gtk_notebook_set_tab_pos()), whether, if there are too many - * tabs to fit the notebook should be made bigger or scrolling - * arrows added (see gtk_notebook_set_scrollable()), and whether there - * will be a popup menu allowing the users to switch pages. - * (see gtk_notebook_popup_enable(), gtk_notebook_popup_disable()) + * ![An example GtkNotebook](notebook.png) + * + * There are many configuration options for `GtkNotebook`. Among + * other things, you can choose on which edge the tabs appear + * (see [method@Gtk.Notebook.set_tab_pos]), whether, if there are + * too many tabs to fit the notebook should be made bigger or scrolling + * arrows added (see [method@Gtk.Notebook.set_scrollable]), and whether + * there will be a popup menu allowing the users to switch pages. + * (see [method@Gtk.Notebook.popup_enable]). * * # GtkNotebook as GtkBuildable - * - * The GtkNotebook implementation of the #GtkBuildable interface + * + * The `GtkNotebook` implementation of the `GtkBuildable` interface * supports placing children into tabs by specifying “tab” as the * “type” attribute of a element. Note that the content * of the tab must be created before the tab can be filled. @@ -87,8 +87,9 @@ * "action-start" or “action-end” as the “type” attribute of the * element. * - * An example of a UI definition fragment with GtkNotebook: - * |[ + * An example of a UI definition fragment with `GtkNotebook`: + * + * ```xml * * * @@ -101,11 +102,11 @@ * * * - * ]| + * ``` * * # CSS nodes * - * |[ + * ``` * notebook * ├── header.top * │ ├── [] @@ -123,9 +124,9 @@ * ├── * ┊ * ╰── - * ]| + * ``` * - * GtkNotebook has a main CSS node with name `notebook`, a subnode + * `GtkNotebook` has a main CSS node with name `notebook`, a subnode * with name `header` and below that a subnode with name `tabs` which * contains one subnode per tab with name `tab`. * @@ -134,7 +135,7 @@ * name `arrow` are placed as first and last child of the `tabs` node. * * The main node gets the `.frame` style class when the notebook - * has a border (see gtk_notebook_set_show_border()). + * has a border (see [method@Gtk.Notebook.set_show_border]). * * The header node gets one of the style class `.top`, `.bottom`, * `.left` or `.right`, depending on where the tabs are placed. For @@ -146,7 +147,7 @@ * * # Accessibility * - * GtkNotebook uses the following roles: + * `GtkNotebook` uses the following roles: * * - %GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget * - %GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs @@ -154,6 +155,11 @@ * - %GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page */ +/** + * GtkNotebookPage: + * + * `GtkNotebookPage` is an auxiliary object used by `GtkNotebook`. + */ #define SCROLL_DELAY_FACTOR 5 #define SCROLL_THRESHOLD 12 @@ -569,6 +575,11 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) object_class->get_property = gtk_notebook_page_get_property; object_class->set_property = gtk_notebook_page_set_property; + /** + * GtkNotebookPage:child: (attributes org.gtk.Property.get=gtk_notebook_page_get_child) + * + * The child for this page. + */ g_object_class_install_property (object_class, CHILD_PROP_CHILD, g_param_spec_object ("child", @@ -576,6 +587,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("The child for this page"), GTK_TYPE_WIDGET, GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY)); + + /** + * GtkNotebookPage:tab: + * + * The tab widget for tihs page. + */ g_object_class_install_property (object_class, CHILD_PROP_TAB, g_param_spec_object ("tab", @@ -583,6 +600,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("The tab widget for this page"), GTK_TYPE_WIDGET, GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY)); + + /** + * GtkNotebookPage:menu: + * + * The label widget displayed in the childs menu entry. + */ g_object_class_install_property (object_class, CHILD_PROP_MENU, g_param_spec_object ("menu", @@ -590,6 +613,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("The label widget displayed in the child’s menu entry"), GTK_TYPE_WIDGET, GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT_ONLY)); + + /** + * GtkNotebookPage:tab-label: + * + * The text of the tab widget. + */ g_object_class_install_property (object_class, CHILD_PROP_TAB_LABEL, g_param_spec_string ("tab-label", @@ -597,6 +626,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("The text of the tab widget"), NULL, GTK_PARAM_READWRITE)); + + /** + * GtkNotebookPage:menu-label: + * + * The text of the menu widget. + */ g_object_class_install_property (object_class, CHILD_PROP_MENU_LABEL, g_param_spec_string ("menu-label", @@ -604,6 +639,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("The text of the menu widget"), NULL, GTK_PARAM_READWRITE)); + + /** + * GtkNotebookPage:position: + * + * The index of the child in the parent. + */ g_object_class_install_property (object_class, CHILD_PROP_POSITION, g_param_spec_int ("position", @@ -611,6 +652,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("The index of the child in the parent"), -1, G_MAXINT, 0, GTK_PARAM_READWRITE)); + + /** + * GtkNotebookPage:tab-expand: + * + * Whether to expand the childs tab. + */ g_object_class_install_property (object_class, CHILD_PROP_TAB_EXPAND, g_param_spec_boolean ("tab-expand", @@ -618,6 +665,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("Whether to expand the child’s tab"), FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GtkNotebookPage:tab-fill: + * + * Whether the childs tab should fill the allocated area. + */ g_object_class_install_property (object_class, CHILD_PROP_TAB_FILL, g_param_spec_boolean ("tab-fill", @@ -625,6 +678,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("Whether the child’s tab should fill the allocated area"), TRUE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GtkNotebookPage:reorderable: + * + * Whether the tab is reorderable by user action. + */ g_object_class_install_property (object_class, CHILD_PROP_REORDERABLE, g_param_spec_boolean ("reorderable", @@ -632,6 +691,12 @@ gtk_notebook_page_class_init (GtkNotebookPageClass *class) P_("Whether the tab is reorderable by user action"), FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); + + /** + * GtkNotebookPage:detachable: + * + * Whether the tab is detachable. + */ g_object_class_install_property (object_class, CHILD_PROP_DETACHABLE, g_param_spec_boolean ("detachable", @@ -1051,6 +1116,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) class->reorder_tab = gtk_notebook_reorder_tab; class->create_window = gtk_notebook_create_window; + /** + * GtkNotebook:page: (attributes org.gtk.Property.get=gtk_notebook_get_current_page org.gtk.Property.set=gtk_notebook_set_current_page) + * + * The index of the current page. + */ properties[PROP_PAGE] = g_param_spec_int ("page", P_("Page"), @@ -1059,6 +1129,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) -1, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkNotebook:tab-pos: (attributes org.gtk.Property.get=gtk_notebook_get_tab_pos org.gtk.Property.set=gtk_notebook_set_tab_pos) + * + * Which side of the notebook holds the tabs. + */ properties[PROP_TAB_POS] = g_param_spec_enum ("tab-pos", P_("Tab Position"), @@ -1067,6 +1142,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) GTK_POS_TOP, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkNotebook:show-tabs: (attributes org.gtk.Property.get=gtk_notebook_get_show_tabs org.gtk.Property.set=gtk_notebook_set_show_tabs) + * + * Whether tabs should be shown. + */ properties[PROP_SHOW_TABS] = g_param_spec_boolean ("show-tabs", P_("Show Tabs"), @@ -1074,6 +1154,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) TRUE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkNotebook:show-border: (attributes org.gtk.Property.get=gtk_notebook_get_show_border org.gtk.Property.set=gtk_notebook_set_show_border) + * + * Whether the border should be shown. + */ properties[PROP_SHOW_BORDER] = g_param_spec_boolean ("show-border", P_("Show Border"), @@ -1081,6 +1166,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) TRUE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkNotebook:scrollable: (attributes org.gtk.Property.get=gtk_notebook_get_scrollable org.gtk.Property.set=gtk_notebook_set_scrollable) + * + * If %TRUE, scroll arrows are added if there are too many pages to fit. + */ properties[PROP_SCROLLABLE] = g_param_spec_boolean ("scrollable", P_("Scrollable"), @@ -1088,6 +1178,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkNotebook:enable-popup: + * + * If %TRUE, pressing the right mouse button on the notebook shows a page switching menu. + */ properties[PROP_ENABLE_POPUP] = g_param_spec_boolean ("enable-popup", P_("Enable Popup"), @@ -1096,7 +1191,7 @@ gtk_notebook_class_init (GtkNotebookClass *class) GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); /** - * GtkNotebook:group-name: + * GtkNotebook:group-name: (attributes org.gtk.Property.get=gtk_notebook_get_group_name org.gtk.Property.set=gtk_notebook_set_group_name) * * Group name for tab drag and drop. */ @@ -1107,6 +1202,11 @@ gtk_notebook_class_init (GtkNotebookClass *class) NULL, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkNotebook:pages: (attributes org.gtk.Property.get=gtk_notebook_get_pages) + * + * A selection model with the pages. + */ properties[PROP_PAGES] = g_param_spec_object ("pages", P_("Pages"), @@ -1197,7 +1297,7 @@ gtk_notebook_class_init (GtkNotebookClass *class) _gtk_marshal_BOOLEAN__ENUM_BOOLEANv); /** * GtkNotebook::page-reordered: - * @notebook: the #GtkNotebook + * @notebook: the `GtkNotebook` * @child: the child #GtkWidget affected * @page_num: the new page number for @child * @@ -1219,7 +1319,7 @@ gtk_notebook_class_init (GtkNotebookClass *class) _gtk_marshal_VOID__OBJECT_UINTv); /** * GtkNotebook::page-removed: - * @notebook: the #GtkNotebook + * @notebook: the `GtkNotebook` * @child: the child #GtkWidget affected * @page_num: the @child page number * @@ -1241,7 +1341,7 @@ gtk_notebook_class_init (GtkNotebookClass *class) _gtk_marshal_VOID__OBJECT_UINTv); /** * GtkNotebook::page-added: - * @notebook: the #GtkNotebook + * @notebook: the `GtkNotebook` * @child: the child #GtkWidget affected * @page_num: the new page number for @child * @@ -1264,7 +1364,7 @@ gtk_notebook_class_init (GtkNotebookClass *class) /** * GtkNotebook::create-window: - * @notebook: the #GtkNotebook emitting the signal + * @notebook: the `GtkNotebook` emitting the signal * @page: the tab of @notebook that is being detached * * The ::create-window signal is emitted when a detachable @@ -1274,9 +1374,9 @@ gtk_notebook_class_init (GtkNotebookClass *class) * a notebook where the tab will be attached. It is also * responsible for moving/resizing the window and adding the * necessary properties to the notebook (e.g. the - * #GtkNotebook:group-name ). + * `GtkNotebook`:group-name ). * - * Returns: (transfer none): a #GtkNotebook that @page should be + * Returns: (transfer none): a `GtkNotebook` that @page should be * added to, or %NULL. */ notebook_signals[CREATE_WINDOW] = @@ -1783,9 +1883,9 @@ gtk_notebook_reorder_tab (GtkNotebook *notebook, /** * gtk_notebook_new: * - * Creates a new #GtkNotebook widget with no pages. + * Creates a new `GtkNotebook` widget with no pages. - * Returns: the newly created #GtkNotebook + * Returns: the newly created `GtkNotebook` */ GtkWidget* gtk_notebook_new (void) @@ -3323,12 +3423,12 @@ gtk_notebook_drag_drop (GtkDropTarget *dest, /** * gtk_notebook_detach_tab: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: a child * * Removes the child from the notebook. * - * This function is very similar to gtk_notebook_remove_page(), + * This function is very similar to [method@Gtk.Notebook.remove_page], * but additionally informs the notebook that the removal * is happening as part of a tab DND operation, which should * not be cancelled. @@ -5572,9 +5672,9 @@ gtk_notebook_menu_label_unparent (GtkWidget *widget) */ /** * gtk_notebook_append_page: - * @notebook: a #GtkNotebook - * @child: the #GtkWidget to use as the contents of the page - * @tab_label: (allow-none): the #GtkWidget to be used as the label + * @notebook: a `GtkNotebook` + * @child: the `GtkWidget` to use as the contents of the page + * @tab_label: (allow-none): the `GtkWidget` to be used as the label * for the page, or %NULL to use the default label, “page N” * * Appends a page to @notebook. @@ -5596,15 +5696,15 @@ gtk_notebook_append_page (GtkNotebook *notebook, /** * gtk_notebook_append_page_menu: - * @notebook: a #GtkNotebook - * @child: the #GtkWidget to use as the contents of the page - * @tab_label: (allow-none): the #GtkWidget to be used as the label + * @notebook: a `GtkNotebook` + * @child: the `GtkWidget` to use as the contents of the page + * @tab_label: (allow-none): the `GtkWidget` to be used as the label * for the page, or %NULL to use the default label, “page N” * @menu_label: (allow-none): the widget to use as a label for the * page-switch menu, if that is enabled. If %NULL, and @tab_label * is a #GtkLabel or %NULL, then the menu label will be a newly * created label with the same text as @tab_label; if @tab_label - * is not a #GtkLabel, @menu_label must be specified if the + * is not a `GtkLabel`, @menu_label must be specified if the * page-switch menu is to be used. * * Appends a page to @notebook, specifying the widget to use as the @@ -5629,8 +5729,8 @@ gtk_notebook_append_page_menu (GtkNotebook *notebook, /** * gtk_notebook_prepend_page: - * @notebook: a #GtkNotebook - * @child: the #GtkWidget to use as the contents of the page + * @notebook: a `GtkNotebook` + * @child: the `GtkWidget` to use as the contents of the page * @tab_label: (allow-none): the #GtkWidget to be used as the label * for the page, or %NULL to use the default label, “page N” * @@ -5653,9 +5753,9 @@ gtk_notebook_prepend_page (GtkNotebook *notebook, /** * gtk_notebook_prepend_page_menu: - * @notebook: a #GtkNotebook - * @child: the #GtkWidget to use as the contents of the page - * @tab_label: (allow-none): the #GtkWidget to be used as the label + * @notebook: a `GtkNotebook` + * @child: the `GtkWidget` to use as the contents of the page + * @tab_label: (allow-none): the `GtkWidget` to be used as the label * for the page, or %NULL to use the default label, “page N” * @menu_label: (allow-none): the widget to use as a label for the * page-switch menu, if that is enabled. If %NULL, and @tab_label @@ -5686,9 +5786,9 @@ gtk_notebook_prepend_page_menu (GtkNotebook *notebook, /** * gtk_notebook_insert_page: - * @notebook: a #GtkNotebook - * @child: the #GtkWidget to use as the contents of the page - * @tab_label: (allow-none): the #GtkWidget to be used as the label + * @notebook: a `GtkNotebook` + * @child: the `GtkWidget` to use as the contents of the page + * @tab_label: (allow-none): the `GtkWidget` to be used as the label * for the page, or %NULL to use the default label, “page N” * @position: the index (starting at 0) at which to insert the page, * or -1 to append the page after all other pages @@ -5743,9 +5843,9 @@ gtk_notebook_mnemonic_activate_switch_page (GtkWidget *child, /** * gtk_notebook_insert_page_menu: - * @notebook: a #GtkNotebook - * @child: the #GtkWidget to use as the contents of the page - * @tab_label: (allow-none): the #GtkWidget to be used as the label + * @notebook: a `GtkNotebook` + * @child: the `GtkWidget` to use as the contents of the page + * @tab_label: (allow-none): the `GtkWidget` to be used as the label * for the page, or %NULL to use the default label, “page N” * @menu_label: (allow-none): the widget to use as a label for the * page-switch menu, if that is enabled. If %NULL, and @tab_label @@ -5783,7 +5883,7 @@ gtk_notebook_insert_page_menu (GtkNotebook *notebook, /** * gtk_notebook_remove_page: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @page_num: the index of a notebook page, starting * from 0. If -1, the last page will be removed. * @@ -5814,9 +5914,10 @@ gtk_notebook_remove_page (GtkNotebook *notebook, * gtk_notebook_next_page * gtk_notebook_prev_page */ + /** - * gtk_notebook_get_current_page: - * @notebook: a #GtkNotebook + * gtk_notebook_get_current_page: (attributes org.gtk.Method.get_property=page) + * @notebook: a `GtkNotebook` * * Returns the page number of the current page. * @@ -5837,7 +5938,7 @@ gtk_notebook_get_current_page (GtkNotebook *notebook) /** * gtk_notebook_get_nth_page: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @page_num: the index of a page in the notebook, or -1 * to get the last page * @@ -5871,7 +5972,7 @@ gtk_notebook_get_nth_page (GtkNotebook *notebook, /** * gtk_notebook_get_n_pages: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * * Gets the number of pages in a notebook. * @@ -5887,8 +5988,8 @@ gtk_notebook_get_n_pages (GtkNotebook *notebook) /** * gtk_notebook_page_num: - * @notebook: a #GtkNotebook - * @child: a #GtkWidget + * @notebook: a `GtkNotebook` + * @child: a `GtkWidget` * * Finds the index of the page which contains the given child * widget. @@ -5922,8 +6023,8 @@ gtk_notebook_page_num (GtkNotebook *notebook, } /** - * gtk_notebook_set_current_page: - * @notebook: a #GtkNotebook + * gtk_notebook_set_current_page: (attributes org.gtk.Method.set_property=page) + * @notebook: a `GtkNotebook` * @page_num: index of the page to switch to, starting from 0. * If negative, the last page will be used. If greater * than the number of pages in the notebook, nothing @@ -5954,10 +6055,11 @@ gtk_notebook_set_current_page (GtkNotebook *notebook, /** * gtk_notebook_next_page: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` + * + * Switches to the next page. * - * Switches to the next page. Nothing happens if the current page is - * the last page. + * Nothing happens if the current page is the last page. */ void gtk_notebook_next_page (GtkNotebook *notebook) @@ -5979,10 +6081,11 @@ gtk_notebook_next_page (GtkNotebook *notebook) /** * gtk_notebook_prev_page: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * - * Switches to the previous page. Nothing happens if the current page - * is the first page. + * Switches to the previous page. + * + * Nothing happens if the current page is the first page. */ void gtk_notebook_prev_page (GtkNotebook *notebook) @@ -6014,13 +6117,13 @@ gtk_notebook_prev_page (GtkNotebook *notebook) * gtk_notebook_get_scrollable */ /** - * gtk_notebook_set_show_border: - * @notebook: a #GtkNotebook + * gtk_notebook_set_show_border: (attributes org.gtk.Method.set_property=show-border) + * @notebook: a `GtkNotebook` * @show_border: %TRUE if a bevel should be drawn around the notebook * * Sets whether a bevel will be drawn around the notebook pages. + * * This only has a visual effect when the tabs are not shown. - * See gtk_notebook_set_show_tabs(). */ void gtk_notebook_set_show_border (GtkNotebook *notebook, @@ -6042,11 +6145,10 @@ gtk_notebook_set_show_border (GtkNotebook *notebook, } /** - * gtk_notebook_get_show_border: - * @notebook: a #GtkNotebook + * gtk_notebook_get_show_border: (attributes org.gtk.Method.get_property=show-border) + * @notebook: a `GtkNotebook` * * Returns whether a bevel will be drawn around the notebook pages. - * See gtk_notebook_set_show_border(). * * Returns: %TRUE if the bevel is drawn */ @@ -6059,8 +6161,8 @@ gtk_notebook_get_show_border (GtkNotebook *notebook) } /** - * gtk_notebook_set_show_tabs: - * @notebook: a #GtkNotebook + * gtk_notebook_set_show_tabs: (attributes org.gtk.Method.set_property=show-tabs) + * @notebook: a `GtkNotebook` * @show_tabs: %TRUE if the tabs should be shown * * Sets whether to show the tabs for the notebook or not. @@ -6119,11 +6221,10 @@ gtk_notebook_set_show_tabs (GtkNotebook *notebook, } /** - * gtk_notebook_get_show_tabs: - * @notebook: a #GtkNotebook + * gtk_notebook_get_show_tabs: (attributes org.gtk.Method.get_property=show-tabs) + * @notebook: a `GtkNotebook` * * Returns whether the tabs of the notebook are shown. - * See gtk_notebook_set_show_tabs(). * * Returns: %TRUE if the tabs are shown */ @@ -6221,12 +6322,11 @@ gtk_notebook_update_tab_pos (GtkNotebook *notebook) } /** - * gtk_notebook_set_tab_pos: - * @notebook: a #GtkNotebook. + * gtk_notebook_set_tab_pos: (attributes org.gtk.Method.set_property=tab-pos) + * @notebook: a `GtkNotebook`. * @pos: the edge to draw the tabs at * - * Sets the edge at which the tabs for switching pages in the - * notebook are drawn. + * Sets the edge at which the tabs are drawn. */ void gtk_notebook_set_tab_pos (GtkNotebook *notebook, @@ -6246,11 +6346,10 @@ gtk_notebook_set_tab_pos (GtkNotebook *notebook, } /** - * gtk_notebook_get_tab_pos: - * @notebook: a #GtkNotebook + * gtk_notebook_get_tab_pos: (attributes org.gtk.Method.get_property=tab-pos) + * @notebook: a `GtkNotebook` * - * Gets the edge at which the tabs for switching pages in the - * notebook are drawn. + * Gets the edge at which the tabs are drawn. * * Returns: the edge at which the tabs are drawn */ @@ -6263,8 +6362,8 @@ gtk_notebook_get_tab_pos (GtkNotebook *notebook) } /** - * gtk_notebook_set_scrollable: - * @notebook: a #GtkNotebook + * gtk_notebook_set_scrollable: (attributes org.gtk.Method.set_property=scrollable) + * @notebook: a `GtkNotebook` * @scrollable: %TRUE if scroll arrows should be added * * Sets whether the tab label area will have arrows for @@ -6292,11 +6391,10 @@ gtk_notebook_set_scrollable (GtkNotebook *notebook, } /** - * gtk_notebook_get_scrollable: - * @notebook: a #GtkNotebook + * gtk_notebook_get_scrollable: (attributes or.gtk.Method.get_property=scrollable) + * @notebook: a `GtkNotebook` * * Returns whether the tab label area has arrows for scrolling. - * See gtk_notebook_set_scrollable(). * * Returns: %TRUE if arrows for scrolling are present */ @@ -6318,11 +6416,12 @@ gtk_notebook_get_scrollable (GtkNotebook *notebook) /** * gtk_notebook_popup_enable: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` + * + * Enables the popup menu. * - * Enables the popup menu: if the user clicks with the right - * mouse button on the tab labels, a menu with all the pages - * will be popped up. + * If the user clicks with the right mouse button on the tab labels, + * a menu with all the pages will be popped up. */ void gtk_notebook_popup_enable (GtkNotebook *notebook) @@ -6353,7 +6452,7 @@ gtk_notebook_popup_enable (GtkNotebook *notebook) /** * gtk_notebook_popup_disable: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * * Disables the popup menu. */ @@ -6393,10 +6492,11 @@ gtk_notebook_popup_disable (GtkNotebook *notebook) /** * gtk_notebook_get_tab_label: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the page * * Returns the tab label widget for the page @child. + * * %NULL is returned if @child is not in @notebook or * if no tab label has specifically been set for @child. * @@ -6423,12 +6523,13 @@ gtk_notebook_get_tab_label (GtkNotebook *notebook, /** * gtk_notebook_set_tab_label: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the page * @tab_label: (allow-none): the tab label widget to use, or %NULL * for default tab label * * Changes the tab label for @child. + * * If %NULL is specified for @tab_label, then the page will * have the label “page N”. */ @@ -6501,7 +6602,7 @@ gtk_notebook_set_tab_label (GtkNotebook *notebook, /** * gtk_notebook_set_tab_label_text: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the page * @tab_text: the label text * @@ -6524,15 +6625,15 @@ gtk_notebook_set_tab_label_text (GtkNotebook *notebook, /** * gtk_notebook_get_tab_label_text: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: a widget contained in a page of @notebook * * Retrieves the text of the tab label for the page containing * @child. * - * Returns: (nullable): the text of the tab label, or %NULL if the tab label - * widget is not a #GtkLabel. The string is owned by the widget and must not be - * freed. + * Returns: (nullable): the text of the tab label, or %NULL if + * the tab label idget is not a `GtkLabel`. The string is owned + * by the widget and must not be freed. */ const char * gtk_notebook_get_tab_label_text (GtkNotebook *notebook, @@ -6553,14 +6654,14 @@ gtk_notebook_get_tab_label_text (GtkNotebook *notebook, /** * gtk_notebook_get_menu_label: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: a widget contained in a page of @notebook * * Retrieves the menu label widget of the page containing @child. * - * Returns: (nullable) (transfer none): the menu label, or %NULL if the - * notebook page does not have a menu label other than the default (the tab - * label). + * Returns: (nullable) (transfer none): the menu label, or %NULL + * if the notebook page does not have a menu label other than + * the default (the tab label). */ GtkWidget* gtk_notebook_get_menu_label (GtkNotebook *notebook, @@ -6582,7 +6683,7 @@ gtk_notebook_get_menu_label (GtkNotebook *notebook, /** * gtk_notebook_set_menu_label: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the child widget * @menu_label: (allow-none): the menu label, or %NULL for default * @@ -6627,7 +6728,7 @@ gtk_notebook_set_menu_label (GtkNotebook *notebook, /** * gtk_notebook_set_menu_label_text: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the child widget * @menu_text: the label text * @@ -6653,16 +6754,16 @@ gtk_notebook_set_menu_label_text (GtkNotebook *notebook, /** * gtk_notebook_get_menu_label_text: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the child widget of a page of the notebook. * * Retrieves the text of the menu label for the page containing * @child. * - * Returns: (nullable): the text of the tab label, or %NULL if the widget does - * not have a menu label other than the default menu label, or the menu label - * widget is not a #GtkLabel. The string is owned by the widget and must not be - * freed. + * Returns: (nullable): the text of the tab label, or %NULL if + * the widget does not have a menu label other than the default + * menu label, or the menu label widget is not a `GtkLabel`. + * The string is owned by the widget and must not be freed. */ const char * gtk_notebook_get_menu_label_text (GtkNotebook *notebook, @@ -6712,14 +6813,15 @@ gtk_notebook_child_reordered (GtkNotebook *notebook, /** * gtk_notebook_reorder_child: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: the child to move * @position: the new position, or -1 to move to the end * * Reorders the page containing @child, so that it appears in position - * @position. If @position is greater than or equal to the number of - * children in the list or negative, @child will be moved to the end - * of the list. + * @position. + * + * If @position is greater than or equal to the number of children in + * the list or negative, @child will be moved to the end of the list. */ void gtk_notebook_reorder_child (GtkNotebook *notebook, @@ -6776,8 +6878,8 @@ gtk_notebook_reorder_child (GtkNotebook *notebook, } /** - * gtk_notebook_set_group_name: - * @notebook: a #GtkNotebook + * gtk_notebook_set_group_name: (attributes org.gtk.Method.set_property=group-name) + * @notebook: a `GtkNotebook` * @group_name: (allow-none): the name of the notebook group, * or %NULL to unset it * @@ -6806,12 +6908,13 @@ gtk_notebook_set_group_name (GtkNotebook *notebook, } /** - * gtk_notebook_get_group_name: - * @notebook: a #GtkNotebook + * gtk_notebook_get_group_name: (attributes org.gtk.Method.get_property=group-name) + * @notebook: a `GtkNotebook` * * Gets the current group name for @notebook. * - * Returns: (nullable) (transfer none): the group name, or %NULL if none is set + * Returns: (nullable) (transfer none): the group name, + * or %NULL if none is set */ const char * gtk_notebook_get_group_name (GtkNotebook *notebook) @@ -6823,8 +6926,8 @@ gtk_notebook_get_group_name (GtkNotebook *notebook) /** * gtk_notebook_get_tab_reorderable: - * @notebook: a #GtkNotebook - * @child: a child #GtkWidget + * @notebook: a `GtkNotebook` + * @child: a child `GtkWidget` * * Gets whether the tab can be reordered via drag and drop or not. * @@ -6847,8 +6950,8 @@ gtk_notebook_get_tab_reorderable (GtkNotebook *notebook, /** * gtk_notebook_set_tab_reorderable: - * @notebook: a #GtkNotebook - * @child: a child #GtkWidget + * @notebook: a `GtkNotebook` + * @child: a child `GtkWidget` * @reorderable: whether the tab is reorderable or not * * Sets whether the notebook tab can be reordered @@ -6885,8 +6988,8 @@ gtk_notebook_set_tab_reorderable (GtkNotebook *notebook, /** * gtk_notebook_get_tab_detachable: - * @notebook: a #GtkNotebook - * @child: a child #GtkWidget + * @notebook: a `GtkNotebook` + * @child: a child `GtkWidget` * * Returns whether the tab contents can be detached from @notebook. * @@ -6909,15 +7012,15 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook, /** * gtk_notebook_set_tab_detachable: - * @notebook: a #GtkNotebook - * @child: a child #GtkWidget + * @notebook: a `GtkNotebook` + * @child: a child `GtkWidget` * @detachable: whether the tab is detachable or not * * Sets whether the tab can be detached from @notebook to another * notebook or widget. * - * Note that 2 notebooks must share a common group identificator - * (see gtk_notebook_set_group_name()) to allow automatic tabs + * Note that two notebooks must share a common group identificator + * (see [method@Gtk.Notebook.set_group_name]) to allow automatic tabs * interchange between them. * * If you want a widget to interact with a notebook through DnD @@ -6926,34 +7029,34 @@ gtk_notebook_get_tab_detachable (GtkNotebook *notebook, * will fill the selection with a GtkWidget** pointing to the child * widget that corresponds to the dropped tab. * - * Note that you should use gtk_notebook_detach_tab() instead of - * gtk_notebook_remove_page() if you want to remove the tab from - * the source notebook as part of accepting a drop. Otherwise, - * the source notebook will think that the dragged tab was - * removed from underneath the ongoing drag operation, and - * will initiate a drag cancel animation. + * Note that you should use [method@Gtk.Notebook.detach_tab] instead + * of [method@Gtk.Notebook.remove_page] if you want to remove the tab + * from the source notebook as part of accepting a drop. Otherwise, + * the source notebook will think that the dragged tab was removed + * from underneath the ongoing drag operation, and will initiate a + * drag cancel animation. * - * |[ - * static void - * on_drag_data_received (GtkWidget *widget, - * GdkDrop *drop, - * GtkSelectionData *data, - * guint time, - * gpointer user_data) - * { - * GtkDrag *drag; - * GtkWidget *notebook; - * GtkWidget **child; + * ```c + * static void + * on_drag_data_received (GtkWidget *widget, + * GdkDrop *drop, + * GtkSelectionData *data, + * guint time, + * gpointer user_data) + * { + * GtkDrag *drag; + * GtkWidget *notebook; + * GtkWidget **child; * - * drag = gtk_drop_get_drag (drop); - * notebook = g_object_get_data (drag, "gtk-notebook-drag-origin"); - * child = (void*) gtk_selection_data_get_data (data); + * drag = gtk_drop_get_drag (drop); + * notebook = g_object_get_data (drag, "gtk-notebook-drag-origin"); + * child = (void*) gtk_selection_data_get_data (data); * - * // process_widget (*child); + * // process_widget (*child); * - * gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child); - * } - * ]| + * gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child); + * } + * ``` * * If you want a notebook to accept drags from other widgets, * you will have to set your own DnD code to do it. @@ -6984,13 +7087,16 @@ gtk_notebook_set_tab_detachable (GtkNotebook *notebook, /** * gtk_notebook_get_action_widget: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @pack_type: pack type of the action widget to receive * - * Gets one of the action widgets. See gtk_notebook_set_action_widget(). + * Gets one of the action widgets. + * + * See [method@Gtk.Notebook.set_action_widget]. * - * Returns: (nullable) (transfer none): The action widget with the given - * @pack_type or %NULL when this action widget has not been set + * Returns: (nullable) (transfer none): The action widget + * with the given @pack_type or %NULL when this action + * widget has not been set */ GtkWidget* gtk_notebook_get_action_widget (GtkNotebook *notebook, @@ -7003,13 +7109,15 @@ gtk_notebook_get_action_widget (GtkNotebook *notebook, /** * gtk_notebook_set_action_widget: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @widget: a #GtkWidget * @pack_type: pack type of the action widget * - * Sets @widget as one of the action widgets. Depending on the pack type - * the widget will be placed before or after the tabs. You can use - * a #GtkBox if you need to pack more than one widget on the same side. + * Sets @widget as one of the action widgets. + * + * Depending on the pack type the widget will be placed before + * or after the tabs. You can use a `GtkBox` if you need to pack + * more than one widget on the same side. */ void gtk_notebook_set_action_widget (GtkNotebook *notebook, @@ -7040,12 +7148,12 @@ gtk_notebook_set_action_widget (GtkNotebook *notebook, /** * gtk_notebook_get_page: - * @notebook: a #GtkNotebook + * @notebook: a `GtkNotebook` * @child: a child of @notebook * - * Returns the #GtkNotebookPage for @child. + * Returns the `GtkNotebookPage` for @child. * - * Returns: (transfer none): the #GtkNotebookPage for @child + * Returns: (transfer none): the `GtkNotebookPage` for @child */ GtkNotebookPage * gtk_notebook_get_page (GtkNotebook *notebook, @@ -7065,8 +7173,8 @@ gtk_notebook_get_page (GtkNotebook *notebook, } /** - * gtk_notebook_page_get_child: - * @page: a #GtkNotebookPage + * gtk_notebook_page_get_child: (attributes org.gtk.Method.get_property=child) + * @page: a `GtkNotebookPage` * * Returns the notebook child to which @page belongs. * @@ -7151,14 +7259,17 @@ gtk_notebook_pages_new (GtkNotebook *notebook) } /** - * gtk_notebook_get_pages: - * @notebook: a #GtkNotebook + * gtk_notebook_get_pages: (attributes org.gtk.Method.get_property=pages) + * @notebook: a `GtkNotebook` * - * Returns a #GListModel that contains the pages of the notebook, - * and can be used to keep an up-to-date view. - * + * Returns a `GListModel` that contains the pages of the notebook. + * + * This can be used to keep an up-to-date view. The model also + * implements [iface@Gtk.SelectionModel] and can be used to track + * and modify the visible page. + * Returns: (transfer full) (attributes element-type=GtkNotebookPage): a - * #GListModel for the notebook's children + * `GListModel` for the notebook's children */ GListModel * gtk_notebook_get_pages (GtkNotebook *notebook) diff --git a/gtk/gtknotebook.h b/gtk/gtknotebook.h index d219f78c42..73139d6580 100644 --- a/gtk/gtknotebook.h +++ b/gtk/gtknotebook.h @@ -44,13 +44,6 @@ G_BEGIN_DECLS #define GTK_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_NOTEBOOK_PAGE, GtkNotebookPage)) #define GTK_IS_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_NOTEBOOK_PAGE)) -/** - * GtkNotebookPage: - * - * A page in the #GtkNotebook. - * - * The `GtkNotebookPage` structure only contains private data. - */ typedef struct _GtkNotebookPage GtkNotebookPage; /** @@ -58,7 +51,7 @@ typedef struct _GtkNotebookPage GtkNotebookPage; * @GTK_NOTEBOOK_TAB_FIRST: the first tab in the notebook * @GTK_NOTEBOOK_TAB_LAST: the last tab in the notebook * - * The parameter used in the action signals of #GtkNotebook. + * The parameter used in the action signals of `GtkNotebook`. */ typedef enum { -- 2.30.2